iT邦幫忙

2023 iThome 鐵人賽

DAY 26
0
自我挑戰組

前端工程師在 Qiita 閱讀的雜食筆記系列 第 26

Day26 - 擁有 20 多年工程師經驗的我,在撰寫設計規格書時所注意的事情

  • 分享至 

  • xImage
  •  

原文連結:エンジニア歴20数年の私が、設計書を書く際に心がけていること - Qiita

上一篇主要介紹設計規格書的「內部設計流程」,接下來這篇文章,將著重於規格書的寫法。

先是從個人角度統整觀點,如何提升文件的易讀性,以及如何避免資訊混淆;在團隊開發中,如何制定一致的「規格書撰寫方式」,使其易於後續維護。

以下正文開始。


前言

時間過得真快,轉眼間我已經在 IT 行業度過了四分之一個世紀。

在這段時間裡,我寫過大量的「設計文件(規格書)」,但內心仍充滿困惑和迷惘。

儘管如此,俗話說「亀の甲より年(薑是老的辣)」,我試著從「個人」和「團隊」兩種角度總結出經驗法則。

  • 本文的主題是「針對設計規格書,開發文件的撰寫方式」
  • 本文假定的規格書,是以 Excel 或 Word 撰寫成正式的(≒ 交付物)設計文件。
  • 因此,比起以自家服務開發或敏捷開發為前提,委託開發、瀑布式開發可能更適合本文內容。

<請注意>

本文內容是作者個人見解,並不代表所屬公司的立場、策略、意見。

個人所注意的事情

在文章開頭說明該文件的建立目的和定位

  • 例如「本書將描述 ◯◯ 功能中 ×× 畫面的佈局設計以及輸入輸出設計」。
  • 若有相關文件,可以寫上「關於 △△,請參考 □□」。
  • 特別適用於設計階段之後(例如系統測試、維護或新增功能時),「搜尋」設計文件的情況。

首先考慮章節架構

  • 考慮章節架構,也可以說是設計一份設計文件。
  • 如果可以,最好在只寫出章節標題的狀態,給合適的人過目,如此可以降低基本認知差異的風險。

先顯示整體 → 再解釋細節

  • 這不僅適用於設計文件和發表文稿,任何文件檔也同樣適用。

注意每行的字數

  • 有些人會在 A4 橫向格式中,寫很長的文句,但這將導致閱讀困難。
  • 每行最佳文字數
    • 如果用 Google 搜尋,可以發現許多網站文章,對橫向書寫的建議是每行 30〜35 個字。
    • 以我來看,設計文件最多不超過 40 個字,這是為了易讀性和每頁資訊量之間的平衡。
      • 40 個字並沒有明確的根據,但如果是「一行 80 字節」,可能會讓人有所感觸⋯⋯
    • 字數可以根據個人的基準來決定,重點是「需要注意每行文字」這一點。

縮短句子

  • 長句子往往形成複雜的結構,容易產生誤解。
  • 個人建議以「每句不超過兩行(即 80 個字符以內)」為目標。對於跨越三行的句子,應該考慮是否能進行拆解。

使用條列式

  • 列舉項目的長句,通常可以轉換為條列式。
  • 在分解結構複雜的句子時,條列式通常非常有效。

使用圖表

  • 比起文字,人類更容易透過圖表直觀理解。
  • 特別是在表現整體概念時,圖表比文字更有說服力。

使用表格

  • 這對預防損害方面非常重要。
  • 若試圖只用文字描述複雜的情況,可能導致讀者產生誤解。

使用縮排(Indentation)

  • 縮排是一種有效的方式,可以讓讀者在視覺上理解文章結構。

統一主語

  • 「當 ◯◯ 按鈕被點擊時,將顯示 ×× 畫面」和「當點擊 ◯◯ 按鈕時,×× 畫面將被顯示」的主語是不同的。
  • 在設計文件中,通常主語是「系統」或「用戶」。雖然沒有必要堅持哪一種,但至少在文件中要保持一致。
  • 順帶一提,我在設計文件中傾向於使用「系統」作為主語。

統一用詞

  • 對於相同功能、相同概念,應該使用完全相同的詞彙,不要用不同的詞彙來描述同一件事。
    • 例:「日締め」、「日次締め」、「日締処理」(代表截止日期)
  • 這些看似小事,但在系統開發中,團隊成員之間微小的認知差異,往往會引發大問題。
  • 在專案中建立詞彙表。
  • 對於縮寫也要在詞彙表中記錄,或在文件開頭寫上「Ruby on Rails(以下簡稱 RoR)」等內容。(除非是已經廣泛使用的縮寫,如「IT」等)

不要創造新詞

  • 常見例子是與日期相關的詞。
    • 「執行日期」、「處理日期」、「當日」⋯⋯
      • 是從哪裡取得?包含時刻嗎?時區是什麼?是否有曆法差異?
  • 如果是專案內共享的概念,請在詞彙表中記錄定義。
  • 如果是在該文件內,獨自建立的詞語,應該建立該詞語的定義項目,並明確做記錄。

排除寫法不一致

例如:

  • 「サーバ」和「サーバー」:統一拼音
  • 「Web」和「ウェブ」:名詞統一使用中、英或日文表示
  • 「4月」、「4月」和「四月」:數字統一用半形、全形或中文表示
  • 「です・ます」和「だ・である」:句尾型態統一

如果是自己專用的筆記,可能不太需要在意這些細節。
但我認為,考慮有讀者存在,以「也許會有人根據這些細節來評價文件的好壞」為前提會比較保險。

專有名詞必須準確

  • 例如「JAVA」是錯誤寫法,正確是「Java」。
  • 對於產品名稱或公司名稱,容易出現混淆的情況,應該仔細查證,確保文字大小寫、單詞間有無空格等內容。

在領導團隊時所注意的事情

我認為,影響設計文件好壞的因素,比起個人的努力和心態,團隊之間的協力更為重要。

如果整個團隊在撰寫設計文件時沒有統一感,對於外部觀察者而言,設計文件的整體價值將會降低。

確認記錄的細節

  • 對於基本設計文件和詳細設計文件,應該要記錄什麼,以及寫到什麼程度。
  • 如果寫得過於詳細,將難以進行維護,最終導致沒有人會查看設計文件。

確認章節的記錄方式

這裡提供一個範例:

1.xxx
    1.1.xxx
        1.1.1.xxx
            (1)xxx

無論是使用全形/半形文字,以及是否使用縮排等細節,都需要仔細確認,這將有助於文件的統一性。

在量產規格書之前先製作樣本

  • 最好由設計文件的審查者,也就是工程師來製作樣本。
  • 樣本完成後,除了說「請看一下」以外,最好有一個場合,能夠向所有人解釋希望如何編寫樣本,以及樣本創作者的想法。

模板盡可能簡單

  • 過多的規則將會降低生產效率。
  • 過度拘泥於模板,將會使內容變得膚淺。在某些情況下,自由格式可能更適合表達。
  • 確實格式也是品質的一部分,但製作一個平衡的模板更為重要。

確定如何保留變更歷史紀錄

  • 紅→藍→綠→⋯⋯,有些成員可能會在每次進行變更時,把顏色變得很繽紛。
  • 對此可能會有其他成員抱怨「難以閱讀!」(就是我)。
  • 雖然從 Excel 轉移到 Markdown 等格式,將其納入版本控制系統可能會更好⋯⋯(有時也涉及到政治因素),但可能很難實現。
  • 建立變更歷史紀錄表,並記錄在哪個表的哪個部分,進行了什麼修改,可能是現實的解決方案。

將上述事項整理成指南

  • 使審查更加順利
  • 當成員更換時,能夠順利進行說明
  • 無論有多忙碌,都不應忽視指南的維護

總結

  • 為了提高書寫能力,只有透過訓練。
  • 最重要的是,身邊有人能夠嚴格指導並提供建議。

最後,如果這篇文章有任何不足之處,請在評論等地方告訴我!

(2018 年 2 月 15 日補充)

非常感謝得到許多反饋。

這篇文章僅基於我個人的經驗,可能存在思慮不足之處,也希望能夠根據各位的開發需求進行修改與應用。

我認為,透過教育和指導,可以在團隊內制定一致的「設計規格書撰寫方式」,從而在設計審查中更專注於「設計本身」。

(2018 年 3 月 11 日補充)

關於「每行字數〜」、「縮短句子」和「使用條列式」,已重新審視表達方式,主要內容將保持不變。


上一篇
Day25 - 成為具備需求定義~系統設計能力人才的文章
下一篇
Day27 - [常有的事] 克服「遇到問題卡住時,請立刻提問」的方法
系列文
前端工程師在 Qiita 閱讀的雜食筆記31
圖片
  直播研討會
圖片
{{ item.channelVendor }} {{ item.webinarstarted }} |
{{ formatDate(item.duration) }}
直播中

尚未有邦友留言

立即登入留言